在 .NET 專案引用動態連結程式庫(DLL)的正確方式
TLDR
- 優先使用 NuGet 管理套件，以解決版本控制、Framework 相容性及相依性問題。
- 若必須引用本機 DLL，請建立專屬資料夾（非 bin 目錄）並納入版控，確保所有專案引用同一來源。
- 嚴禁直接從 bin 目錄引用 DLL，否則會導致編譯時來源遺失或多專案版本不一致。
- Website Project (WSP) 需將 .dll.refresh 檔案納入版控，以記錄 DLL 的正確引用來源。
為什麼應優先使用 NuGet 管理套件
在 .NET 開發中，直接引用 DLL 檔案並非最佳實踐。建議優先使用 NuGet，原因如下：
- 版本管理便捷：NuGet 支援輕鬆的升降版操作。
- Framework 相容性：NuGet 會根據專案的 Framework 版本自動選擇最適合的套件版本。
- 自動處理相依性：安裝套件時，NuGet 會自動安裝該套件所依賴的其他套件。
若為公司內部 Library，建議架設內網 NuGet Server，將 Library 打包後上傳，供開發者透過 Visual Studio 連結引用。
本機 DLL 的正確引用方式
當無法使用 NuGet 而必須引用本機 DLL 時，應採取以下步驟以確保協作順暢：
- 建立專屬目錄：在方案層級（或版控根目錄）建立一個專屬資料夾（建議不要命名為 packages，以免與 NuGet 混淆）。
- 統一存放與引用：將所有需要引用的 DLL 檔案放置於此資料夾內，並讓專案統一指向此路徑。
- 納入版控：此資料夾必須納入版控系統，確保團隊成員皆能取得相同的 DLL 版本。
直接引用 bin 目錄的風險
什麼情況下會遇到這個問題：當開發者為了方便，直接從編譯輸出目錄（bin）引用 DLL 檔案時。
- 編譯失敗風險：bin 目錄通常不納入版控。若專案檔 (.csproj) 記錄的引用來源指向 bin 目錄，當清理專案或刪除 bin 目錄後，編譯器將無法找到原始 DLL 檔案，導致無法重新建置。
- 版本不一致：在多專案方案中，若各專案各自從 bin 目錄引用，容易導致不同專案引用到不同版本的 DLL，難以控管。
Website Project (WSP) 的特殊處理
什麼情況下會遇到這個問題：當專案類型為 Website Project (WSP) 時，由於沒有 .csproj 專案檔，引用機制有所不同。
WSP 在加入參考時，會在 bin 目錄產生一個 {DLL名稱}.dll.refresh 檔案，該檔案記錄了 DLL 的實際引用路徑。雖然 bin 目錄本身不上版控，但 .dll.refresh 檔案必須納入版控，以確保其他開發者能正確還原引用來源。
異動歷程
- 初版文件建立。